Primitives
In SimAntics, the opcode of an instruction can either refer to a built-in command, known as a primitive, or to a subroutine. The subroutines can be privates (belong to the object) semiglobals or globals. A global will have an opcode 256 to 4095, a private will have an opcode from 4096 to 8191 and a semiglobal will have an opcode >= 8192. Instructions are executed synchronously within the thread until something yields the thread, an error is fired or the stack becomes empty. An example of this is the Animate Sim primitive. In the behaviours found in the game, this primitive often has a loopback on the false branch which points back to itself. The primitive returns true if the animation is complete and false if it is not. The false then loops back to the Animate Sim primitive to run the next frame. If this code was executed synchronously no animations would ever be observed. Therefore some primitives yield the thread. You can think of primitives as having the following return values. GOTO_TRUE, GOTO_FALSE, ERROR, GOTO_TRUE_YIELD, GOTO_FALSE_YIELD. The documentation below for primitives and their operands is correct for The Sims Online. The Sims 1 and 2 operands may be slightly different. = The Sims Online Primitives = 0 - Sleep Changes the current virtual thread's state to sleeping. The number of ticks to sleep for is determined by a stack variable (local) specified by the operand. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: Stack Var # Unused 1 - Generic Sims Online Call Main article: Generic Sims Online Call This primitive is used to call upon game functions which are either not common enough to include as a primitive or very specialized with no parameters (eg. Disable/Enable Build/Buy). Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: Call ID Unknown (potentially any arguments?) 2 - Expression Performs a logical or mathematical expression. The operator value describes what type of expression to perform and the other values determine the left and right hand side of the expression. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: LhsData RhsData IsSigned Operator LhsOwner RhsOwner The lhsdata, lhsowner, rhsdata and rhsowner are scopes as described here. Possible values for operator: *These only work if the operation is performed on a list! 3 - Report Metric Used to record data. Not sure where this data goes… 4 - grab Places the Stack Object in the Sim's (should be the thread's "Me" reference) slot 0. Operand: No Operand. 5 - drop Attempts to place the caller's held object (in slot 0) on an adjacent tile, starting in front. Operand: No Operand. 6 - Change Suit/Accessory 7 - Refresh Marks an object to be redrawn, update the light map of its room or update the room's room score. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: TargetObj Unused RefreshType Unused TargetObj: * 0 - My * 1 - Stack Object's. RefreshType: * 0 - Graphic * 1 - Lighting Contribution * 2 - Room Score Contribution 8 - Random Number Sets a variable referenced by a Scope to a random number between 0 and a specified value also referenced by a scope. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: DestData DestOwner RangeData RangeScope 9 - burn Spawns a fire object on the specified location if a fire object is not already there and the object on the space is not busy (or the allow busy objects flag is enabled). Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: Location Flags Unused The location can either be 0: Stack Object, 1: in front of stack object or 2: floors under stack object (unused in TSO) There is only one flag: 1: allow busy objects. If this is not enabled the fire will not spread onto objects that are not idle. 10 - Sims1.0 tutorial This primitive isn't used in any of the behaviors found in The Sims Online. 11 - Get Distance To Gets the Pythagorean distance between the stack object and the specified object in tiles, floored. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: Temp # Unknown (Flags?) ObjectScope OScopeData Unknown 12 - Get Direction To Gets the direction from the specified object to the stack object and stores it in the specified Scope. The direction's basis or 0 value "North" is facing from where the house should be AWAY FROM the road. The following values 1-7 are a clockwise rotation around this direction in 45 degree steps, and each has a compass name as you would expect going clockwise corresponding with its direction. The directions of both of the objects are not considered for the calculation, just their positions. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: ResultData ResultOwner Unknown (Flags?) ObjectScope OScopeData 13 - Push Interaction Pushes an Interaction onto the Stack Object's tree queue. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: Interaction # ObjectLocation Priority Flags IconLocation Unknown ObjectLocation's meaning differs based on flags, see below. IconLocation is only regarded when a certain flag is set. Priorities This would be better on the Interactions page, but it will remain here until we understand more about how they work. Flags There is functionality for "Interaction result type" and "Server Only (DEV ONLY!)" but I haven't been able to place these on the operand. 14 - Find Best Object for Function Finds an object by function with the relevant Object Data or advertisement set highest, and with its entry point for that function not set to None. This is used for finding sinks, counters, ovens etc (in conjuncton with Get Distance To). If the object's "lockout count" is greater than 0, the object is ignored. This is used to iterate over all of the objects with the function, usually to find the one with the smallest distance. If the primitive finds an object, the stack object is set to it and the primitive returns true, however if the primitive cannot find any objects, it returns false. This is heavily used by the "Food Chain" group of interactions and NPC service sims. Functions Operand Offset: 0 1 2 3 4 5 6 7 Meaning: Function Unused 15 - Break Point Pauses execution for further examination if the variable specified by a Scope is not 0. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: Data Field Owner Unused 16 - Find Location For Finds a location to place the stack object. Can be along object vectors, out of the world and "smoke cloud", a specific mode used for the attack interaction. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: Mode Local # Flags Unused Modes The possible modes are: Flags 17 - idle for input Behaves like the sleep primitive, but can return early if the object has been "notified" out of idle, in which case it also sets Object Data flag 1«6 "notified by idle for input". One example of this is when an interaction is canceled, or when another object uses the primitive "Notify the Stack Object out of Idle". This is commonly used (with a sleep time of 0) to detect if an interaction has been canceled. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: Local # Allow Push? Unused Local # specifies the Local Variable the number of ticks are taken from. If "Allow Push" is set to 1, this state is "interruptable" and functions can be pushed onto the stack. 18 - Remove Object Instance Removes the object instance specified. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: TargetObj Flags Unused TargetObj: 0 = Me, 1 = Stack Object, 2 = Target (unused) Flags 19 - make new character Makes a new character with the specified Age, Skin Color and Gender. Not used by any objects activated in TSO. Operand (not confirmed) Offset: 0 1 2 3 4 5 6 7 Meaning: AgeLocal SexLocal GenderLocal Unused 20 - Run Functional Tree Run one of several types of functions on the stack object. Used to make sims sit down to eat, wash their hands etc as part of an automatic process. See Primitive 14 - Find Best Object for Function above for a the table of functions that can be referenced. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: Function Flags Unused The only flag seems to be bit 1: change icon. This changes the behavior icon to that of the stack object (imagine using toilet, when going to wash hands icon changes for sink. 21 - show string Presumably used for debug. Some objects show interesting and original strings such as "can't get to the duck", but it doesn't look like these should normally be used. Nothing shows up in The Sims Complete Collection when this primitive is run. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: String Table # (String ID - 1) Unused 22 - look towards 23 - Play Sound Event Plays the specified sound event. Offset: 0 1 2 3 4 5 6 7 Meaning: Event ID Unknown Flags Volume (0-100) Unused Flags: 24 - old relationship Gets the relationship between two objects. Used by the pool table to determine the player number of people and sometimes used by social interactions to keep track of who people are talking to etc. This is an old system for doing this, but objects still use it. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: Get/Set Relationship Var Parameter # Affected Parties Flags Unknown Get/Set determines whether or not the relationship value will be retrieved from or set to the parameter specified by Parameter #. 0 = Get, 1 = Set. Relationship Var determines the relationship variable to access. Not sure what these are right now - looks like each object has its own specific strings! Flags: 1 = fail if too small, 2 = use neighbors 25 - Transfer Funds A more fleshed out version of Alter Budget from The Sims 1, allowing more options such as transfer of funds between people, to maxis, from maxis and to generic objects such as the tip jar! Not sure how this works or what the operand is right now. 26 - Relationship Tracks "relationship" variables of one object to another. Relationships are kept between avatar-lot transfers (not sure about object relationships), so care will have to be taken when storing relationships to avatars (use avatar id instead of object id). Offset: 0 1 2 3 4 5 6 7 Meaning: Relationship Var Mode Flags Local # Variable Scope Variable Data The primitive usually gets/sets the relationship variable into/to the specified variable. Modes There are 4 modes for the Relationship primitive: 0: from me to stack object 1: from stack object to me 2: from stack object to object in local (Specified by Local #) 3: from object in local to stack object (Specified by Local #) Flags 27 - Go To Relative Position 28 - Run Tree by Name This primitive runs the tree referenced by the name in the specified string on either the stack object or itself. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: String Table ID for Tree Names String Scope (1: global, 0: private) Unused String# - 1 Destination Unused Destination Values: 0: run in my stack (non-yielding) 1: run in stack object's stack (non-yielding) 2: push onto my stack (yielding) 29 - Set Motive Change Sets a motive to change at a specific rate until it hits the specified value. You can clear all changes by setting the Clear All? flag. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: PerHrOwner StopValueOwner Target Motive Clear All? PerHrData StopValueData The values for the change per hour and value to stop at are accessed via Scopes. If Clear All? is set, all motive changes on this sim are cleared. The Target Motive uses the same ID format as Motive Data. 30 - Syslog Used to log information from objects. Seems to always log a string from private String Table 308. 31 - Set to Next Sets the specified variable referenced by a Scope to the object ID of the first object it can find (after the last one) using the search parameters. Used to iterate over objects of a specific type, people etc. Returns false after all objects of that type have been iterated over. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: GUID (if applicable) Mode LhsOwner Value LhsData Modes If the highest bit (128) of the Modes field is set the left hand side field is used. If not then the object ID is stored in the stack object. 32 - Test Object Type Tests an object's type against a specified GUID. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: GUID TargetData TargetOwner 33 - find 5 worst motives Places 5 worst motives into temps 0-4. Each temp references a Motive Data entry, and they are ordered by lowest first. Only used twice in TSO… npcportal.iff and pedportal.iff (for determining why a sim decided to leave). Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: Unused Target Motive Type Target: 0 = me, 1 = stack object, 2 = target object (?) Motive Type: 0 = Motive, 1 = Mental Motive, 2 = Physical Motive 34 - ui effect Only used by tutorial to flash buttons. 35 - Special Effect Shows a Picture in Picture display on the specified object (always the stack object). Can also center the camera on an object and slow time down to 1 speed (like the fire). Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: Timeout (seconds) Window Size Zoom Level Flags (Caption STR# - 1) Unused Window Size: 0 = small, 1 = medium, 2 = large Zoom Level: 1 = near, 2 = mid, 3 = far The caption is always read from string table 305. Flags 36 - Dialog - Private Strings Very complicated, not much info on this one and the text exported versions seem to be missing a lot of info. I probably won't be able to get the operand for this one until much later. Dialog Types: Text Entry also has a "filter profanity" flag which causes the text entry to return false on detecting any profanity. Temp can either be 0 or 1. Behavior Engage (OLD) - ??? Continue (OLD) - ??? Engage - ??? Continue - ??? Not sure what the difference between these is. Both are used in their fair share of dialogs. Icon Strings can be set for the Message, Yes Button, No Button, Title, Cancel Button and Icon Name. Each presumably takes up a byte in the operand to reference the relevant string id, leaving 2 bytes for the other data… This will most likely be complicated. Strings are always chosen from string table ID 301 (called "Dialog prim string set"). Do not take any information in this section as final! Local reference Local variable to reference. 37 - Test Sim Interacting With Returns true if this sim is interacting with the Stack Object, false otherwise. Used to allow interactions like "wake up" for sims already sleeping in the tent and disallow it otherwise. Operand: No Operand. 38 - Dialog - Global Strings Same as 36 except instead accessed global strings. TSO only. 39 - Dialog - Semi-Global Strings Same as 36 except instead accessed semi-global strings. TSO only. 40 - OnlineJobsCall Calls one of the built in functions relating to OnlineJobs. Any that require input, like "Is Job Available" use the value in temp 0. Operand (NOT VERIFIED) Offset: 0 1 2 3 4 5 6 7 Meaning: Call# Unused Calls 41 - Set Balloon/Headline Sets the balloon over a Sim's head to display with the specified icon or clear. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: Target Icon # Icon Group Duration (Ticks/Loops) Balloon Type Flags Target: 0 = Me, 1 = Stack Object If Ticks is 0, the Balloon/Headline is cleared. If Ticks is -1 (all bits set), the duration will be forever Flags Balloon Types Balloon Icons See Balloon Icons for a list of these. 42 - Create New Object Instance Creates a new Object Instance with the GUID specified in the location specified. The new object ID is placed in the stack object. If the object cannot be created, the primitive returns false. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: GUID Position Flags Local To Use (if specified) Interaction Callback Interaction Callback Upon running the init function of the created object, if the Return immediately flag is set the Interaction specified by Interaction Callback is queued onto the Stack Object (at the time and same thread this primitive was run) with its Parameter 0 set to the object ID. This is used extensively by the social interaction objects to create AND INIT the objects before running the function from them. This functionality replaces the default where the new object is placed into the stack object, but the primitive still returns true or false depending on whether the creation succeeded or not. A value of 254 means "Call This Tree". Positions Flags (bitfield) 43 - drop onto Drops an object from the specified slot of the Me object onto the specified slot on the Stack Object. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: SrcSlotMode SrcSlotNum DestSlotMode DestSlotNum The mode determines where to get the slot number - 0 for literal and 1 for retrieval from a parameter. 44 - Animate Sim Plays an animation on the thread this primitive is run on's Sim. After playing the animation the primitive acts as an event listener, calling the false branch when an animation event (xevt) is called and the true branch when the animation is finished, and waits in place until one of these happens. When looped back to from the false branch and still playing the animation the primitive will resume event listening. If there have been multiple events since the last time the primitive was listening, it favors the most recent one, or if the animation has already ended, the true branch. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: Animation ID LocalEventNumber Source Flags ExpectedEvents ExpectedEvents should be set to the number of events in the animation, but can be set to 0. If it is 0, it has no effect. If Animation ID is 0, the current animation is stopped. Animation Source Flags The "unknown" flags are: - Interruptable - Hurryable - Full Reset - Behaviour: A 2 bit collection of animation modes, which are: Since the only 2 bit space is 3&4, this probably fits in there. 45 - Go To Routing Slot 46 - Snap Instantly moves the sim to a position retrieved from a routing slot without walking the sim there. Used for objects which move the sim using custom animations (or to positions inside them and back out), like stairs. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: Index Mode Flags Unused Modes The Snap to Routing Slot primitive has multiple modes which allow the primitive to do a variety of things: 0 - Slot Number in parameter: Snaps to a routing slot (type 3) owned by this object, with index specified by the parameter specified by the "Index" part of the operand. 1 - Be contained in stack object: Snaps the sim into containment slot 0 (type 0, index 0) of the stack object. If the object is dragged while in this state, the sim will be attached to the object like a plate is on a table. 2 - Be in front of the stack object: Snaps the sim to be directly in front of the stack object. Direction is supposedly unchanged. 3 - Slot Number: Snaps to a routing slot (type 3) owned by this object, with index specified by the "Index" part of the operand. 4 - Slot Number: Snaps to a global routing slot (type 3), with index specified by the "Index" part of the operand. Flags 1: Origin only 2: Ask person to move (asks sims idling on the snap location to move) 3: Use footprint extensions (???) 47 - reach Plays the appropriate reach animation on the sim depending on object height and if the sim is sitting, and can attempt to grab/drop an item on its animation event. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: Mode Attempt to grab/drop? Slot Param Unused Mode can be: 0: Reach to stack object, 1: Reach to slot on stack object, 2: Reach to mouth (unused) When mode 1 is specified, the slot to reach to is retrieved from the parameter specified by "Slot Param". 48 - Stop ALL Sounds Stops ALL sounds (yes, ALL!) of the specified object. Operand: Offset: 0 1 2 3 4 5 6 7 Meaning: Target Unused Target: 0 = me, 1 = stack object. 49 - Notify the Stack Object out of Idle Signals the Stack Object out of an idle primitive. Works for both idle for input and Sleep. Counters and Fence Objects usually use this to notify other fence objects to change their appearance, but some other objects use it to facilitate group interaction around a single animated parent object (eg. the pool table). Operand No Operand. 50 - Add/Change the Action String Changes the current interaction's name to the specified string. Operand Offset: 0 1 2 3 4 5 6 7 Meaning: String Table ID Unknown (String# - 1) Unused 51 - prim 51 - (used in Sims 2.0) This primitive isn't used in any of the behaviors found in The Sims Online. 52 - prim 52 - (used in Sims 2.0) This primitive isn't used in any of the behaviors found in The Sims Online. 53 - prim 53 - (used in Sims 2.0) This primitive isn't used in any of the behaviors found in The Sims Online. 54 - prim 54 - (used in Sims 2.0) This primitive isn't used in any of the behaviors found in The Sims Online. 55 - Sync Field This primitive isn't used in any of the behaviors found in The Sims Online. 56 - Ownership This primitive isn't used in any of the behaviors found in The Sims Online. 57 - Start Persistant Dialog This primitive isn't used in any of the behaviors found in The Sims Online. 58 - End Persistant Dialog This primitive isn't used in any of the behaviors found in The Sims Online. 59 - Update Persistant Dialog This primitive isn't used in any of the behaviors found in The Sims Online. 60 - Poll Persistant Dialog This primitive isn't used in any of the behaviors found in The Sims Online. 61 - Send Maxis Letter 62 - Invoke Plugin Used to hook an object into a plugin UI, aka an EOD. This is used for interactions such as the pizza table. 63 - Get Terrain Info Gets information on the terrain at the position of a specified object. Can either be Me or the Stack Object. (decided by flags) Operand Offset: 0 1 2 3 4 5 6 7 Meaning: Mode Flags Unused Modes Flags 64 - Leave Lot and Goto This primitive isn't used in any of the behaviors found in The Sims Online. 65 - Find Best Action Same as TS1 Find Best Interaction, though Free Will was never included in TSO so this primitive was initially replaced with Report Metric. This finds the "best" interaction the sim can perform, eg. the one with the highest advertisments for their lowest motives and other factors. Used for cat and dog free will. Presumably just pushes it to their queue once it finds one, since I can't find anything that queues it afterwards… Returns false when no interaction is found (the sim is suitably satisfied with their current motives, or there is no object to cater to them). Operand No Operand. 66 - Set Dynamic Object Name 67 - Inventory Operations